package com.google.gwt.gwtpages.client.page;

import com.google.gwt.gwtpages.client.page.loader.GWTPagesLoader;
import com.google.gwt.gwtpages.client.page.parameters.PageParameters;


/**
 * {@link GWTPagesPresenter} lifecycle event handler interface. Order of events are:
 * <ol>
 * <li> {@link PageEventHandler#onPageRequest(String, String, GWTPageAttributes, PageRequestSession)}</li>
 * <li> {@link PageEventHandler#onPageLoaded(GWTPage)} (usually only once
 * when before the page is cached)</li>
 * <li> {@link PageEventHandler#onPageLoadFailure(String, Throwable)} (only if the page could not be loaded)</li>
 * <li> {@link PageEventHandler#beforePageShow(GWTPage, PageParameters, PageRequestSession)}</li>
 * <li> {@link PageEventHandler#afterPageShow(GWTPage, PageParameters, PageRequestSession)}</li>
 * <li>
 * {@link PageEventHandler#onPageShowSuccess(GWTPage, PageParameters, PageRequestSession)} or
 * {@link PageEventHandler#onPageShowFailure(GWTPage, PageParameters, PageRequestSession)}</li>
 * 
 * @author Joe Hudson
 */
public interface PageEventHandler {

	/**
	 * Event fired after the page
	 * {@link SyncPage#onShowPage(PageParameters, PageRequestSession)} or
	 * {@link AsyncPage#onShowPage(PageParameters, PageRequestSession, AsyncPageCallback)}
	 * methods are called.
	 * 
	 * @param pageLoadResult
	 *            the page and associated data
	 * @param parameters
	 *            the page parameters
	 * @param session
	 *            {@link PageRequestSession}
	 */
	public void afterPageShow(GWTPage pageLoadResult,
			PageParameters parameters, PageRequestSession session);

	/**
	 * Event fired after the page has been sucessfully rendered including all
	 * sync or async data requests that are required to show the page. With an
	 * {@link AsyncPage} ths is called when the page calls the
	 * {@link AsyncPageCallback#onSuccess()} method is called.
	 * 
	 * @param pageLoadResult
	 *            the page and associated data
	 * @param parameters
	 *            the page parameters
	 * @param session
	 *            {@link PageRequestSession}
	 */
	public void onPageShowSuccess(GWTPage pageLoadResult,
			PageParameters parameters, PageRequestSession session);

	/**
	 * Event fired if an error occurs while showing the requested page (but
	 * after the page was loaded correctly from the {@link GWTPagesLoader}. With an
	 * {@link AsyncPage} this is called when the page calls the
	 * {@link AsyncPageCallback#onFailure(Throwable)} method is called.\
	 * 
	 * @param pageLoadResult
	 *            the page and associated data
	 * @param parameters
	 *            the page parameters
	 * @param session
	 *            {@link PageRequestSession}
	 */
	public void onPageShowFailure(GWTPage pageLoadResult,
			PageParameters parameters, PageRequestSession session);

	/**
	 * Event fired when the page has been requested - before the page dealt with
	 * in any way
	 * 
	 * @param pageToken
	 *            the page token (part of the history token without additional
	 *            parameter related information)
	 * @param historyToken
	 *            the full history token
	 * @param metaData
	 *            the {@link GWTPageAttributes}
	 * @param session
	 *            {@link PageRequestSession}
	 * @return true if the page should be loaded and rendered or false if
	 *         processing should stop
	 */
	public boolean onPageRequest(String pageToken, String historyToken,
			GWTPageAttributes metaData, PageRequestSession session);

	/**
	 * Event fired after the {@link GWTPagesPresenter} is loaded but before the page is given
	 * to the {@link ApplicationPresenter}
	 * 
	 * @param pageLoadResult
	 *            the page and associated data
	 * @param parameters
	 *            the page parameters
	 * @param session
	 *            {@link PageRequestSession}
	 * @return true if the page should be loaded and rendered or false if
	 *         processing should stop
	 */
	public boolean beforePageShow(GWTPage pageLoadResult,
			PageParameters parameters, PageRequestSession session);

	/**
	 * Event fired after when the {@link GWTPagesLoader} initially loads the
	 * {@link GWTPagesPresenter}
	 * 
	 * @param pageLoadResult
	 *            the page and associated data
	 */
	public void onPageLoaded(GWTPage result);

	/**
	 * Event fired if a {@link GWTPagesPresenter} is requested but not found
	 * 
	 * @param historyToken
	 *            the history token
	 * @return a replacement page or null if not handled by this handler
	 */
	public void onPageNotFound(String historyToken);

	/**
	 * Event fired if an exception is thrown when loading a {@link GWTPagesPresenter}
	 * 
	 * @param historyToken
	 *            the history token
	 * @param cause
	 *            the error that was thrown
	 * @return a replacement page or null if not handled by this handler
	 */
	public void onPageLoadFailure(String historyToken, Throwable cause);
}
